/*-------------------------------------------------------------------------
 * 前端程序的日志记录框架
 *
 * Copyright (c) 2018-2022, PostgreSQL Global Development Group
 *
 * src/include/common/logging.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef COMMON_LOGGING_H
#define COMMON_LOGGING_H

/*
 * 日志级别仅供信息参考。它们不影响程序流程。
 */
enum pg_log_level
{
	/*
	 * 尚未初始化（不作为实际消息日志级别使用）。
	 */
	PG_LOG_NOTSET = 0,

	/*
	 * 默认情况下通常关闭的低级消息。
	 */
	PG_LOG_DEBUG,

	/*
	 * 任何发送到 stderr 的程序消息，默认显示。（程序的正常输出应发送到 stdout 而不使用日志系统。）
	 */
	PG_LOG_INFO,

	/*
	 * 警告和“几乎”错误，取决于程序
	 */
	PG_LOG_WARNING,

	/*
	 * 错误
	 */
	PG_LOG_ERROR,

	/*
	 * 关闭所有日志记录（不作为实际消息日志级别使用）。
	 */
	PG_LOG_OFF,
};

/*
 * __pg_log_level 是将实际显示的最低日志级别。
 */
extern enum pg_log_level __pg_log_level;

/*
 * 日志消息可以包含多个部分。主要消息是必需的，其他部分是可选的。发出多个部分时，应按此枚举的顺序进行，以保持一致性。
 */
enum pg_log_part
{
	/*
	 * 主要消息。尽量保持在一行；遵循后端的主要消息风格指南。
	 */
	PG_LOG_PRIMARY,

	/*
	 * 附加细节。遵循后端的详细消息风格指南。
	 */
	PG_LOG_DETAIL,

	/*
	 * 有关如何解决问题的提示（不保证正确）。遵循后端的提示消息风格指南。
	 */
	PG_LOG_HINT,
};

/*
 * 一种解决方案，以便能够产生回归测试所需的 psql 输出。
 */
#define PG_LOG_FLAG_TERSE	1

void		pg_logging_init(const char *argv0);
void		pg_logging_config(int new_flags);
void		pg_logging_set_level(enum pg_log_level new_level);
void		pg_logging_increase_verbosity(void);
void		pg_logging_set_pre_callback(void (*cb) (void));
void		pg_logging_set_locus_callback(void (*cb) (const char **filename, uint64 *lineno));

void		pg_log_generic(enum pg_log_level level, enum pg_log_part part,
						   const char *pg_restrict fmt,...)
			pg_attribute_printf(3, 4);
void		pg_log_generic_v(enum pg_log_level level, enum pg_log_part part,
							 const char *pg_restrict fmt, va_list ap)
			pg_attribute_printf(3, 0);

/*
 * 首选样式是使用这些宏进行日志记录；除非在错误接口代码中，否则不要直接调用 pg_log_generic[_v]。
 */
#define pg_log_error(...) \
	pg_log_generic(PG_LOG_ERROR, PG_LOG_PRIMARY, __VA_ARGS__)

#define pg_log_error_detail(...) \
	pg_log_generic(PG_LOG_ERROR, PG_LOG_DETAIL, __VA_ARGS__)

#define pg_log_error_hint(...) \
	pg_log_generic(PG_LOG_ERROR, PG_LOG_HINT, __VA_ARGS__)

#define pg_log_warning(...) \
	pg_log_generic(PG_LOG_WARNING, PG_LOG_PRIMARY, __VA_ARGS__)

#define pg_log_warning_detail(...) \
	pg_log_generic(PG_LOG_WARNING, PG_LOG_DETAIL, __VA_ARGS__)

#define pg_log_warning_hint(...) \
	pg_log_generic(PG_LOG_WARNING, PG_LOG_HINT, __VA_ARGS__)

#define pg_log_info(...) \
	pg_log_generic(PG_LOG_INFO, PG_LOG_PRIMARY, __VA_ARGS__)

#define pg_log_info_detail(...) \
	pg_log_generic(PG_LOG_INFO, PG_LOG_DETAIL, __VA_ARGS__)

#define pg_log_info_hint(...) \
	pg_log_generic(PG_LOG_INFO, PG_LOG_HINT, __VA_ARGS__)

#define pg_log_debug(...) do { \
		if (unlikely(__pg_log_level <= PG_LOG_DEBUG)) \
			pg_log_generic(PG_LOG_DEBUG, PG_LOG_PRIMARY, __VA_ARGS__); \
	} while(0)

#define pg_log_debug_detail(...) do { \
		if (unlikely(__pg_log_level <= PG_LOG_DEBUG)) \
			pg_log_generic(PG_LOG_DEBUG, PG_LOG_DETAIL, __VA_ARGS__); \
	} while(0)

#define pg_log_debug_hint(...) do { \
		if (unlikely(__pg_log_level <= PG_LOG_DEBUG)) \
			pg_log_generic(PG_LOG_DEBUG, PG_LOG_HINT, __VA_ARGS__); \
	} while(0)

/*
 * 一个常见的简写：pg_log_error() 并立即 exit(1)。
 */
#define pg_fatal(...) do { \
		pg_log_generic(PG_LOG_ERROR, PG_LOG_PRIMARY, __VA_ARGS__); \
		exit(1); \
	} while(0)

#endif							/* COMMON_LOGGING_H */
